========
  BgMapper .177 (c)2003 PeekinSot
  SNES Savestate viewer and mapper (speedy and tiny)
  By Dwayne Robinson, using Nasm/WDOSX/Alink
  http://fdwr.tripod.com/snes.htm
  FDwR at hotmail.com

  1. Changes
  2. About
  3. Thanks
  4. Requirements
  5. Parameters
  6. Features
  7. Things left out
  8. Future plans
  9. History

=======
Changes
=======
.177    2003-03-10
- Recompiled to PE format rather than RDOFF
- Added force SNES video mode command line option '-fv #'. Don't know what in
  the world Seiken Densetsu 3 is doing, but for some reason the map screens
  can never be captured during at a point which the video mode is 7 - no
  matter WHAT scanline it is saved on. Maybe ZSNES always saves the state on
  the nearest horizontal interrupt or something funky. So anyway, to force
  those screens visible, you would type (... -fv 7).

.170+
- Bg alignment. In games with 'blocky' levels, like Mario World and Metroid 3,
  the tiles are distinct and easy to align to. In games like DKC and Super
  Star Wars though, it is much more difficult to tell just where the seams
  are. Bg alignment automatically aligns the selected bg to the top left of
  the screen so that you will be on a whole tile, not half of one. It works
  especially well for small areas (like one or two screen rooms). Press '9'
  for the menu.
- Large scene snapshots (512x512) and VERY large (1024x1024=1Mb). No more
  cutting and pasting of 15 separate 320x200 snapshots. This should really
  help with mode 7 and 64x64 tilemap scenes. 512x512 is just right for many
  areas in Zelda. 1024x1024 is perfect for Mario Kart. Press '0' for the
  export menu.
- Some games turn off all the bgs at certain times during the frame, which
  makes it confusing when you start BgMapper and don't see anything, even
  though you know there should be something there. So if none of the bgs are
  turned on, it just turns them all on now.
- Sides clipping, all four sides, all four tile directions, any size tile.
- Simple mouse coloring in graphics viewer. Select the default color to view
  graphics in with a right click on the palette; left click on the color you
  want to "paint" with. Then all tiles painted over in the viewing window will
  retain their colors even when you change the current palette. You can also
  right click on a tile to grab its color. The autopalette does not always get
  the colors correct and also can not color every single tile because not
  every single tile is used in a scene simultaneously so this should help the
  graphics exports look better.
- Autosequencing for all exports, whether scene, VRAM graphics, or palette.
  Files ("bgimg###.bmp", "bgvrm###.bmp", "bgimg###.pal) can now be numbered
  from from 0 to 999.
- Intelligent VRAM formatting divides different sections into their various
  tile formats and attempts to colorize tiles, based on the video mode,
  sprites, bg graphics, and bg tilemaps. The formatting is not always correct
  though. It will get confused with scenes that use multiple types of graphic
  tiles close together in VRAM or switch graphics modes midframe. The
  paletting can misidentify parts of leftover tilemaps and is only able to
  colorize elements which are currently in the scene. If a sprite is not
  visible in the current scene (even if it graphics happen to be in VRAM),
  then its palette is unknown. Press '8' for formatting, '*' to clear all tile
  formatting, '9' to search for used palettes and colorize the tiles, '(' to
  clear all paletting.
- Different tile formats selectable in graphics viewer by pressing 1-4
  (2bpl,4bpl,8bpl,Mode 7).

.160+
- Added palette inversion for scenes using subtraction transparency, like
  "Torchlight Trouble" in "DKC"
- Added raw palette exporting (exactly as is in CGRAM)
- Info screen does not annoyingly switch to text mode
- 16x16 tiles used in "Yoshi's Island" backgrounds and "Slayers"
- Fixed a cache problem where scenes with too many tiles overflowed the buffer
  and eventually corrupted other tiles. A good example was the DKC2 main map
  screen. Mixing 8x8 and 16x16 tiles in the cache was also fixed.


=====
About
=====
  BgMapper is a simple program which can recreate the still scene from an
  emulator's savestate (ZSNES), tell miscellaneous technical details about the
  display, and show the hidden scene graphics used to build the scene. Its
  eventual intended purpose is to output tilemaps from the scene that can be
  pieced together to make complete levels. This should lead to an original
  idea: complete map collections of classic SNES games.

  For the longest time, I wanted to map out all those classic console games
  that provided me so many hours of fun. Thanks to emulation, I finally have
  the chance to. All the levels you see while playing a game have to be stored
  somewhere, and if you could just find where, you could get the complete
  maps. Unfortunately, it's difficult to find them in the cartridge ROM since
  each game stores its levels in different areas using its own compression
  format. While the game is running though, everything is in an expanded state
  in either memory (WRAM, SNES memory) for faster access or the scene itself
  (VRAM). So what BgMapper does is display the scene in video memory from a
  savestate (complete snapshots of the SNES state).

  Some games can store the whole current area in the scene, like one-screen
  levels in "Mario World", smaller areas of "Zelda:LTTP", and whole racetracks
  from "Mario Kart". Others keep only a 'window' and simply generate new parts
  when they need to (like when the scene is scrolled or you enter a new area).
  So only the tiles that you can visibly see are mappable. That means visiting
  every little screen of a level and saving its state to map it all (just a
  bit tedious!).

  Excuse me for my favortism to the Super Nintendo, but BgMapper could someday
  be rewritten to include other consoles (if I'm ambitious enough to get
  familiar with how they all work). 

Disclaimer
----------
  The only cost of this program is suggestions for improvement, bug reports,
  and a letter of appreciation :)  It is provided as freeware, in appreciation
  of all the free utilities others have written which I use and enjoy.

  Although this program does not have any known problems, it is not guaranteed
  to be free of unknown ones. You use this program by your own choice. I
  disclaim any responsibility from damage to your computer this program could
  cause. If you do encounter anything though, please tell me so it can be
  fixed! After all, I use this on my computer too :/

  You may not resell this program; however, you MAY reverse engineer,
  decompile, or disassemble it if you so please. If you're going to that much
  trouble though, just ask me for the source ;)


======
Thanks
======
- Yoshi for his informative docs that got me started.
- Vilewrath for writing the example SNES tile translating code in
  BASIC.
- ZsKnight for sending me the ZSNES savestate format
  and info on screen addition and subtraction!
- Qwertie for organizing his conversations with various emulator
  authors and writing his own very helpful doc.
- All the authors of emulators.
- All the places out there that keep info, like 'The Emulation
  Center', 'Zophar's Domain', 'Snes Programmer's Resource'...
- Michael Tippach for WdosX, a 32bit DOS extender.
- Authors of NASM for a great compiler.
- Gaz for his useful assembly library.


============
Requirements
============
  To recreate an entire scene, BgMapper must be able to handle all video modes
  and most tilemap settings. So it is sort of like just the graphics core of
  an emulator (not that the graphics code of any emulator is a small part!).
  The high memory and speed requirements of an emulator do not apply here,
  because the entire ROM does not need to be loaded (just a much smaller
  savestate), and there is no CPU to emulate (only a tile based graphics scene
  to build).

File to view
------------
  Simply include the ZSNES savestate (or movie) to view after the program
  name. It has no file loader from inside.

  bgmapper zelda.zs2
  bgmapper metroid3.zmv
  bgmapper c:\dw\emu\allstars.zs9

System
--------
  You'll need P4 2GHz or greater, but that should not be a problem for any of
  you, right? Just kidding. I wrote this to work on my pitiful old 25MHz 386,
  so anything more than that is all the better.

- PC 386+    You surely have that covered if you even downloaded this
             (unless you're a Mac user)
- 4Mb        It doesn't really even use one megabyte of that
- VGA        SVGA is not supported, just 320x200:256
- Keyboard   Always handy to have one of these things
- Mouse      Not that useful yet


==========
Parameters
==========
  BgMapper accepts the following command line parameters:

-info        Prints the savestate information (video mode, bitdepths, active
             screens...) and quits.
-fv          Forces a specific SNES video mode 0-7. Useful for some games that
             change video modes during frames.
-h -?        Shows usage and command line parameters
-sd          Mostly useless now. Shows few extra messages during startup.


========
Features
========
  Ok, here is why you bothered to download this program:

- Still Scene Viewing   (the coolest:)
- Graphics Viewing
- Graphics Exporting
- Technical Information (I'm sure nobody cares about this;)
- Palette exporting

Still Scene Viewing
-------------------
  The main part of the program. The scene is the same one you would see on the
  screen of your emulator when you saved the state, unless the game is using
  any realtime effects that change the scene midframe (as most annoyingly do).
  It currently supports:

  - Bitplane video modes 0-6 (4,16,256 colors)
  - Mode 7 as flat scene
  - 32x32 32x64 64x32 64x64 128x128(mode 7) tilemaps
  - 8x8 and 16x16 tilesize
  - Tile flipping, paletting, and layer priority
  - Subscreen/mainscreen layering
  - Background color constant
  - Mode 0 separate palettes per bg

  You can pan around the scene and see the junk you weren't supposed to, turn
  on/off bgs (even ones that are purposely disabled), and then export a
  snapshot when you have the picture you want visible.

  Although it displays the extra wide screens of modes 5&6, the tiles are the
  wrong size (they should be genuine 16x8 tiles). Color addition/subtraction
  is absent, and sprites are also missing.

  One important note on what you see in the scene: When you save it determines
  what you get. Sadly (for our mapmaking purposes), the majority of games use
  at least some type of HDMA effects. That means in a split screen like the
  map of 'Secret Of Mana', you will catch either the sky or the ground,
  depending on what scanline the state was saved. Oddly ZSNES .400 saves on
  scanline 0 while ZSNES .815 saves on 223. To save it at the scanline you
  want, you will have to use the debugger. Just trace through it until the Y
  count goes a little beyond the vertical line you where think the change is
  happening.

    Up Down Left Right   Scroll by a single tile (eight pixels)
    PgUp PgDn Home End   Scroll by half a page (128 pixels)
    * / + -              Fine adjustment (1 pixel)

    1-4          Toggle on/off mainscreens. You can even turn on bgs that the
                 game turned off, although you will likely just see junk.
    Shift+(1-4)  Toggle on/off subscreens.
    6            Restore all bgs to as they were before you started messing
                 with them.
    7            Merge all screens into main layer. Can be very useful for
                 improving visibility in some scenes that use transparency.
                 Was mainly added for "Metroid 3". Too bad ZSNES did not have
                 such a key.
    8            Invert palette. For scenes that use subtraction transparency
                 like "Torchlight Trouble" in "DKC".
    9            Bg alignment.
    0            Export menu for exporting image of scene, game palette, or
                 graphics.
    F1           Little reminder if you forget the keys

Graphics Viewing
----------------
  The graphics are interesting to look at if you like to see what building
  blocks make up the scene and how games pack their graphics. You can also see
  the 256 color palette and select which palette group to view the graphics
  with. It can view all formats the SNES uses in VRAM.

  One thing you will immediately notice is that the graphics are in the wrong
  colors. That is because the color information for the graphics is stored
  separately from the actual graphics, whether in the tilemap array or sprite
  table. To fix that, you can either have BgMapper attempt to colorize it or
  color it manually.

  VRAM formatting divides different sections into their various tile formats
  and attempts to colorize tiles, based on the video mode, sprites, bg
  graphics, and bg tilemaps. The formatting is not always correct though,
  since it will get confused with scenes that use multiple types of graphic
  tiles close together in VRAM or switch graphics modes midframe. The
  paletting can misidentify parts of leftover tilemaps and is only able to
  colorize elements which are currently in the scene. If a sprite is not
  visible in the current scene (even if it graphics happen to be in VRAM),
  then its palette is unknown.

  So you can also do it yourself. Select the default color to view graphics in
  with a right click on the palette; left click on the color you want to
  "paint" with. Then all tiles painted over in the viewing window will retain
  their colors even when you change the current palette. You can also right
  click on a tile to grab its color.

    Up Down      Scroll one row
    Left Right   Scroll one tile

    + -          Change palette (step depends on the current format)
    h            Toggle hex/dec offset

    1-4          Change tile format: 2bpl, 4bpl, 8bpl, Mode 7
    8 *          Format/Unformat
    9 (          Palette/Unpalette
    0            Save all VRAM graphics (bgvrm000.bmp)

                 Tile Window   Color Blocks
    left click   colorize      select color palette
    right click  grab color    change default palette

Graphics exporting
------------------
  Have you have ever wanted to have maps of "Zelda", "ChronoTrigger", "Final
  Fantasy 2", "Tales of Phantasia", or "Secret of Mana"? If so, you're quite
  out of luck with the 'Save Snapshot' feature of any emulator, since it saves
  it exactly as you see it, scaled, rotated, skewed, warped... While these
  games do a commendable job of setting the perspective, top-down is the best
  for maps; and that is how the Scene Viewer exports them. Another
  shortcoming, the scene 'window' of the SNES is only 256x224 even though
  interestingly games often store more than that in the scene (a full
  1024x1024 map for mode 7). So BgMapper has the option of a LARGE snapshot.

  How about ever wanting to build a game of your own based on an existing tile
  set, rather than draw your own by hand? Maybe you have wanted to use
  familiar characters in your little odyssey. You can export all of VRAM to a
  bitmap, to play with however you want. Of course, you are (or at least
  should be) well aware that they are copyrighted. Therefore, I do not
  consider myself responsible for you getting yourself in trouble by ripping
  off some game company's graphics and putting them in your own game ;)

  Exported files ("bgimg###.bmp", "bgvrm###.bmp", "bgimg###.pal) are numbered
  from from 0 to 999.

Technical Information
---------------------
  For anyone who actually cares, this is a little info page for various
  registers. To display the information about a savestate scene without
  starting up BgMapper, use the '-info' switch.

Palette Exporting
-----------------
  You can export the CGRAM palette exactly as is (15bit color, word per entry,
  512 bytes), or as an expanded RGB palette (64 shade, three bytes per entry,
  768 bytes) for whatever use may come to mind.


===============
Things left out
===============
  Certain features have been intentionally left out, since they are special
  effects that just hinder mapmaking:

- Mode 7 rotation and scaling
- Windowing
- Pixelation (scrambling, mosaic effect)
- HDMA effects

  Windowing and HDMA effects could be added, but it would be difficult since
  they are real-time effects that would require BgMapper to be even more of an
  emulator and simulate a complete frame. The lack of HDMA means that a lot of
  scenes will not appear exactly as they do in emulation, (with no wavy
  effects, skewing, midframe palette changes, and such) but will instead look
  flat and plain. Of course, that is exactly what we want! Ironically what the
  emulation authors strive so hard to perfect is the very thing that I've
  intentionally removed.


============
Future plans
============
  Things to be done that I'm probably too lazy to finish:

- Map data exporting
- Sprites in Scene Viewing
- A few more details added to Scene Info
- Rare 8x16 tiles used in "Secret of Mana" opening screen
- Transparency (color addition and subtraction)

Map Exporting
-------------
  I'll come up with a special format just for map files, and eventually a
  separate map editor. This simple program is supposed to only be for simply
  getting the map out of the savestate, nothing more. The map files will have
  to be able to hold multiple maps, tile sets, palettes, and have some sort of
  compression method for keeping the filesize down. It will also need to
  include multiple layering for those maps that use two overlayed planes such
  as "Zelda", "Secret of Mana", "Mario RPG"... It could even have a way to
  link separate maps together and mark special areas of the map with text
  comments, but don't get your hopes up. Something like that that would not
  come for quite a while, unless one of you out there wants to write it ;-)

Sprites
-------
  It does not really need to show them, but why not?

More info
---------
  Some more scene information like what the windows are set to, what DMA
  channels are active, and the values in the mode 7 registers would be nice to
  know (to me anyway, none of you likely care:).

16x8 tiles
-----------
  16x8 tiles such as the ones in the main menu of 'Secret of Mana', although
  very rare, will be added. They are the double wide tiles used the for the
  512 column video modes.

Transparency
------------
  It isn't necessary, but it makes thing look so much better. Then again, is
  it really worth the coding?

Anything else
-------------
  If I didn't mention something above, then I don't plan to add it (but I
  guess if it is something good, you can ask anyway).


=======
History
=======
  Nothing interesting for most of you:

--===Ver 0.0===-- (Aug 5,1998)
- Start writing viewer in Qbasic. Figure out where certain registers of the
  SNES were stored in ZSNES savestates.
- Write code for simple GUI parts (menus and lists).
- Create main menu and file loading window.
- Add mouse support (it was a must).
- Able to load VRAM, OAM, and scroll registers but not able to display even a
  single tile yet.
- Get the scene info page right after some trial and error. Tells the tile
  size, map size, and scroll registers.
- Add palette viewing window.
- Map tiles are now flipped vertically and horizontally.
- Added mosaic, vertical scan line, and cycle count info. Verified that other
  games can be viewed with ZMapper in addition to Zelda.
- Added different colorbases for each plane while using mode 0.
- Start to add sprites (to the Sprites page at least, not the scene).
- Add checking that files to be loaded are indeed ZSNES savestates. That means
  it will not load a non-savestate file even if the name ends with the 'zst'
  extension.

--===Ver 0.01===--
- Write a tile translator (SNES tile => linear bitmap).
- Try to figure out how tilemaps are arranged with simple colored blocks. They
  are messed up! Instead of 64x64 tilemaps being normal, simple arrays they
  are four separate 32x32 tilemaps.
- Replace the blocks with real tiles (at least for non-mode 7 8x8 tiles).
- Add palette colormapping.
- Replace the tilemap debugger with the real one to draw scene layers.
- Add sprites list with details (they might not be right though).
- Get the tilemaps to wrap correctly!
- Add View scene scroll with arrow keys.
- Beat Mario RPG and decide I want to make a map of it!

--===Ver 0.02===--
- Added background color, now the skies in 'Mario World' and 'AllStars' look
  as they should!
- Metroid scenes now display correctly. I had the tilemap height/width bits
  reversed, so 32x32 and 64x64 tilemaps worked fine, but 32x64 and 64x32 were
  not wrapping right at the edges.
- Fixed bug where tilemaps that point to tiles past VRAM should wrap around to
  the front (for 'Yoshi's Island').
- Found the first game yet to use 16x16 tiles (also Yoshi's Island)
- now I can finally test them out...ok, they work.
- Add background color to palette viewer.
- My compiler just told me that ZMapper's source code was too big, so I guess
  it's time to convert it to some other language.

--===Ver 0.10===-- (assembly version)
- It now draws boxes (oh yeah) and has two types of neat fonts, but there
  isn't even a title page yet. How did ZsKnight do it all?
- Mouse and keyboard routines written.
- The menu now works (or at least it is drawn right and reacts to key input),
  and rather nicely too for being written in tedious assembly.
- Do some major revising of the readme, maybe because I'm so tired of coding.
- Get the mouse to work with the menus, both clicking on the choices and
  moving over it the them.
- Time tested several tile translators and think I've found the fastest one.
  It is not necessarily as fast as an emulator's tile translator(s) because it
  works for any bitplane mode (color depths 1,2,3,4,& 8), rather than having
  individual ones for each different depth, but it isn't meant to beat
  emulators!
- Decide to change the name of this prog to BgMapper in case people get it
  confused with ZSNES and think it was written by the same people. It was
  named after Zelda, but this program applies to much more than just one game,
  so this name should be more fitting. A month has gone by and this is all
  I've done?

--===Ver 0.11===--
- Get the complete format for ZSNES savestates from ZsKnight
- Get info from ZsKnight on color addition/subtraction
- It finally loads ZSNES savestates! A cheap test blit some VRAM tiles onto
  the screen. Compared the tile blitting with Naga, and it's about twice as
  fast. That's good enough for me.
- Take a break and work on side project 'SpriteView' in assembly. Actually Sv
  was spawned from a downsized BgMapper :)

--===Ver 0.12===-- (Nov 19)
- Add a simple palette window to VRAM viewer.
- Add -sd "status display" switch.
- Added dumb scene info output - not finished by any means.
- Add raw tilemap viewer page.
- Adapt tilemap viewer code to make simple multilayered scene viewer. It can
  accept 2,4,8bit modes.
- It finally renders the resemblance of a scene, but still need to add tile
  paletting, flipping, priority, and other tile sizes.
- Scene viewer can scroll bgs, supporting 32x32, 32x64, 64x32, and 64x64
  tilemaps sizes.
- Added mode flat mode 7 scene viewing.

--===Ver 0.13===-- (Feb 10)
- Tile priority,
- flipping, and
- paletting all work now

--===Ver 0.14===-- (April 8)
- Tile cache added to speed things up
- Starts out viewing scene rather than needing to select it from the menu
- Fixed background color constant addition. The skies look right now, although
  it seems that ZSNES might not always save the color constant in the
  savestate for some reason.
- Added scene export to a bitmap

--===Ver 0.15===---
- Subscreen/mainscreen layering fixed
- Allow mainscreens and subscreens to be toggled on/off
- Set key for merging screens of games that use transparency. Should greatly
  improve viewing in some cases (press 7)
- Add little messages to let you know what happens
- Palette exporting (also by pressing 0)
- Different color palettes for each bg in mode 0
- '-info' startup switch

--===Ver 0.16===---
- Nicer looking scene viewing keyhelp
- VRAM graphics exporting, all sprites and tilesets
  (by pressing 0 in graphics viewer or selecting from scene export menu)


(:Peekin:)  eof || ^Z
